home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The World of Computer Software
/
The World of Computer Software.iso
/
pcl4c341.zip
/
PCL4C.REF
< prev
next >
Wrap
Text File
|
1993-01-01
|
61KB
|
2,283 lines
Personal Communications Library
For the C Language
(PCL4C)
REFERENCE MANUAL
Version 3.4
Jan 4, 1993
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1993
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice 205-881-4630
FAX 205-881-4630
BBS 205-880-9748
PCL4C Reference Manual Page 1
C O N T E N T S
Chapter Page
Table of Contents.............................2
Introduction..................................3
SioBaud....................................4
SioBrkKey..................................5
SioBrkSig..................................6
SioCrtWrite................................7
SioCTS.....................................8
SioDCD.....................................9
SioDelay..................................10
SioDone...................................11
SioDSR....................................12
SioDTR....................................13
SioError..................................14
SioFIFO...................................15
SioFlow...................................16
SioGetc...................................17
SioKeyPress...............................18
SioKeyRead................................19
SioInfo...................................20
SioIRQ....................................21
SioLine...................................22
SioLoopBack...............................23
SioModem..................................24
SioParms..................................25
SioPutc...................................26
SioRead...................................27
SioReset..................................28
SioRI.....................................29
SioRTS....................................30
SioRxBuf..................................31
SioRxFlush................................32
SioRxQue..................................33
SioTimer..................................34
SioUART...................................35
SioUnGetc.................................36
Function Summary.............................37
Error Code Summary...........................38
PCL4C Reference Manual Page 2
Introduction
This manual lists all of the PCL4C functions in alphabetical
order. Every library function will return a value as follows:
1. Negative values for error conditions. See last page of this
manual for a list of error values and their meanings.
2. Non-negative values when returning data (eg: SioLine).
3. Zero otherwise.
When debugging an application, be sure to test all return values.
Use SioError to print the associated text for errors.
Example Code Segment
*****************************************************************
* int Code; /* MUST be 'int', not 'char' */ *
* *
* Code = SioFunction( ); /* any PCL4C function */ *
* if(Code<0) *
* {/* error returned */ *
* SioError(Code); /* SioError prints error text */ *
* SioDone(Port); /* always call SioDone last */ *
* exit(1); *
* } *
* /* no errors */ *
* ...your application code... *
* *
*****************************************************************
For more examples, examine each of the example programs provided
(SIMPLE.C and TERM.C). Also look at the examples associated with
each library function described in the following section.
Refer to the User's Manual (PCL4C.USR) for addition information.
PCL4C Reference Manual Page 3
SioBaud
Function Sets the baud rate of the selected port.
Syntax int SioBaud(Port,BaudCode)
int Port; /* Port selected (COM1 - COM4) */
int BaudCode; /* Baud code */
Remarks The SioBaud function sets the baud rate without
resetting the port. It is used to change the baud rate
after calling SioReset.
Baud Code Baud Rate PCL4C.H Name
0 300 Baud300
1 600 Baud600
2 1200 Baud1200
3 2400 Baud2400
4 4800 Baud4800
5 9600 Baud9600
6 19200 Baud19200
7 38400 Baud38400
8 57600 Baud57600
9 115200 Baud115200
Returns -4 : Port out of range. Expected 0 to 3.
-11 : Bad baud rate code. See above code values.
Example /* do auto baud detect */
for(Code=0;Code<10;Code++)
{/* set baud rate & transmit 'A' */
SioBaud(Port,Code);
SioPutc(Port,'A');
/* assume other side echos back */
if(SioGetc(Port,18)=='A'))
{puts("Baud rate detected");
/*...do something here...*/
}
}
See Also SioReset
PCL4C Reference Manual Page 4
SioBrkKey
Function Return non-zero if the Control-BREAK key was pressed.
Syntax int SioBrkKey()
Remarks The SioBrkKey function returns a TRUE value (non-
zero) if the Control-BREAK key was pressed, else it
returns a zero. Use SioBrkKey as a safety exit from a
polling loop. Don't mix this function up with
SioBrkSig.
Returns -1 : Control-BREAK was pressed.
0 : Control-BREAK was NOT pressed.
Example int c;
...
while(1)
{/* exit if user pressed Control-BREAK */
if(SioBrkKey())
{puts("User typed Contrl-BREAK");
SioDone(Port);
exit(1);
}
/* transmit any typed character */
if(SioKeyPress())
{c = SioKeyRead();
SioPutc(Port,c);
}
/* display any incoming character */
c = SioGetc(Port,0);
if(c!=-1) SioCrtWrite(c);
}
See Also SioBrkSig
PCL4C Reference Manual Page 5
SioBrkSig
Function Asserts, cancels, or detects BREAK signal.
Syntax int SioBrkSig(Port,Cmd)
int Port; /* Port selected (COM1 thru COM4) */
char Cmd; /* ASSERT, CANCEL, or DETECT */
Remarks The SioBrkSig function controls the BREAK bit in the
line status register. The legal commands are:
ASSERT_BREAK ('A') to assert BREAK
CANCEL_BREAK ('C') to cancel BREAK
DETECT_BREAK ('D') to detect BREAK
ASSERT_BREAK, CANCEL_BREAK, and DETECT_BREAK are
defined in PCL4C.H. See TERM.C for an example of the
use of SioBrkSig.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expected 0 to 3.
-6 : Illegal command. Expected 'A', 'C', or 'D'.
>0 : BREAK signal detected (DETECT command only)
Example /* Assert BREAK for 1 second */
SioBrkSig(Port,ASSERT_BREAK);
SioDelay(18);
SioBrkSig(Port,CANCEL_BREAK);
/* Detect BREAK */
if(SioBrkSig(Port,DETECT_BREAK))
{puts("BREAK signal detected");
/* ...do some more stuff... */
}
See Also SioBrkKey
PCL4C Reference Manual Page 6
SioCrtWrite
Function Write character to the screen.
Syntax int SioCrtWrite(ch)
char ch; /* character to write */
Remarks The SioCrtWrite function uses the BIOS to write a
single character to the screen at the current cursor
location.
SioCrtWrite calls the BIOS directly without any
intermediate buffering or processing. It is usually
faster than a call to the C library.
Returns zero
Example /* wait up to 1 second (18 tics) for character */
if( (c = SioGetc(COM1,18)) != -1)
{/* echo to screen */
SioCrtWrite(c);
}
See Also SioKeyPress and SioKeyRead
PCL4C Reference Manual Page 7
SioCTS
Function Reads the Clear to Send (CTS) modem status bit.
Syntax int SioCTS(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioCTS function is used to read the Clear to Send
(CTS) modem status bit.
The CTS line is used by some error correcting modems
to implement hardware flow control. CTS is dropped by
the modem to signal the computer not to send data, and
is raised to signal the computer to continue.
Refer to the User's Manual for a discussion of flow
control.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expected 0 to 3.
0 : CTS is clear.
>0 : CTS is set.
Example /* wait for CTS to go active */
while(1)
{if(SioCTS(Port)) break;
if(SioBrkKey())
{puts("Aborted by user");
SioDone(Port);
exit(1);
}
}
/* now we can send the character */
SioPutc(Port,ch);
See Also SioFlow, SioDSR, SioRI, SioDCD, and SioModem.
PCL4C Reference Manual Page 8
SioDCD
Function Reads the Data Carrier Detect (DCD) modem status bit.
Syntax int SioDCD(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioDCD function is used to read the Data Carrier
Detect (DCD) modem status bit. Also see SioModem.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expected 0 to 3.
0 : DCD is clear.
>0 : DCD is set.
Example /* test data carrier status bit */
if(SioDCD(Port))
puts("Carrier is on");
else puts("Carrier is off");
See Also SioDSR, SioCTS, SioRI, and SioModem.
PCL4C Reference Manual Page 9
SioDelay
Function Delays one or more tics.
Syntax int SioDelay(tics)
int tics; /* # tics */
Remarks The SioDelay function is used to delay one or more
timer tics, where each timer tic is approximately 55
milliseconds (18 tics to the second).
Returns zero
Example /* delay 5 seconds */
SioDelay(5*18);
See Also SioTimer
PCL4C Reference Manual Page 10
SioDone
Function Terminates further serial processing.
Syntax int SioDone(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioDone function terminates further serial
processing. SioDone MUST be called before exiting your
application so that interrupts can be restored to
their original state. Failure to do this can crash
the operating system. If you forget to call SioDone
before exiting, be sure to re-boot your computer. You
can call SioDone even if SioReset has not been called,
so it is good practice to always call SioDone before
exiting your application.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expected 0 to 3.
Example /* terminate processing for COM3 */
SioDone(COM3);
See Also SioReset.
PCL4C Reference Manual Page 11
SioDSR
Function Reads the Data Set Ready (DSR) modem status bit.
Syntax int SioDSR(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioDSR function is used to read the Data Set Ready
(DSR) modem status bit.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expected 0 to 3.
0 : DSR is clear.
>0 : DSR is set
Example /* read DSR status bit */
if(SioDSR(Port))
puts("Modem is ready");
else puts("Modem is not ready");
See Also SioCTS, SioRI, SioDCD, and SioModem
PCL4C Reference Manual Page 12
SioDTR
Function Set, clear, or read the Data Terminal Ready (DTR) bit.
Syntax int SioDTR(Port,Cmd)
int Port; /* Port selected (COM1 thru COM4) */
char Cmd; /* DTR command (SET, CLEAR, or READ) */
Remarks The SioDTR function controls the Data Terminal Ready
(DTR) bit in the modem control register. Commands
(defined in PCL4C.H) are:
SET_LINE ('S') to set DTR (ON)
CLEAR_LINE ('C') to clear DTR (OFF)
READ_LINE ('R') to read DTR
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expected 0 to 3.
-5 : Not one of 'S', 'C', or 'R'.
0 : DTR is OFF (READ_LINE Command).
>0 : DTR is ON (READ_LINE Command).
Example /* turn DTR on for modem connected to COM4 */
SioDTR(COM4,SET);
See Also SioRTS.
PCL4C Reference Manual Page 13
SioError
Function Displays error in text.
Syntax int SioError(Code)
int Code; /* Error code returned from */
/* a PCL4C function */
Remarks The SioError function displays the error in text
corresponding to the error code. During development
of a communications application, it is a good idea to
always test return codes, and print out their
descriptions with SioError.
Returns zero
Example code = SioReset(Port,Baud4800);
/* display error message if error occurred */
if(code<0) SioError(code);
PCL4C Reference Manual Page 14
SioFIFO
Function Sets the FIFO trigger level (INS16550 only).
Syntax int SioFIFO(Port,LevelCode)
int Port; /* Port selected (COM1 thru COM4) */
int LevelCode; /* FIFO level code (see below) */
Remarks The SioFIFO function is used to set the trigger level
at which interrupts are generated. For example, if the
FIFO level is set to 8, then the INS16550 UART will
not generate an interrupt until 8 bytes have been
received. This reduces the number of interrupts
generated and allows faster processing with slower
machines or when running simultaneous ports.
In order to test if your port is a INS16550, call
SioFIFO with a LevelCode of other than FIFO_OFF.
SioFIFO can be called for the INS8250/16450 without
ill effect.
Code PCL4C.H Name Trigger Level
-1 FIFO_OFF Disable FIFO
0 LEVEL_1 1 byte
1 LEVEL_4 4 bytes
2 LEVEL_8 8 bytes
3 LEVEL_14 14 bytes
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expected 0 to 3.
>0 : FIFO level set.
0 : FIFO level not set (not INS16550).
Example /* Set FIFO level to 8 */
if( SioFIFO(Port,LEVEL_8) ) printf("FIFO reset\n");
else printf("UART in not INS16550\n");
PCL4C Reference Manual Page 15
SioFlow
Function Sets hardware (RTS/CTS) flow control.
Syntax int SioFlow(Port,Tics)
int Port; /* Port selected (COM1 thru COM4) */
int Tics; /* SioPutc timeout tics */
Remarks The SioFlow function is used to enable or disable
hardware flow control. Hardware flow control uses RTS
and CTS to control data flow between the modem and the
computer. Refer to the User's Manual for a discussion
of flow control. To enable hardware flow control,
call SioFlow with Tics > 0.
"Tics" is the number of timer tics (18 per second)
before a call to SioPutc will time out because the
modem dropped CTS.
In order for hardware flow control to work correctly,
your modem must also be configured to work with
hardware flow control, and your computer to modem
cable must have RTS and CTS wired straight through. If
you enable hardware flow control, do not modify the
RTS line (by calling SioRTS) unless you know exactly
what you are doing.
Flow control is disabled after resetting a port. To
explicitly disable hardware flow control, call SioFlow
with Tics = -1.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expected 0 to 3.
=0 : Flow control disabled.
>0 : Flow control enabled.
Example /* Enable flow control on COM1 */
Code = SioFlow(COM1,18);
if(Code>0) printf("Flow Control enabled\n");
else SioError(Code);
/* disable flow control on COM2 */
Code = SioFlow(COM2,-1);
if(Code==0) printf("Flow Control disabled\n");
else SioError(Code);
See Also SioPutc
PCL4C Reference Manual Page 16
SioGetc
Function Reads the next character from the serial line.
Syntax int SioGetc(Port,Tics)
int Port; /* COM1 to COM4 */
int Tics; /* # timer tics */
Remarks The SioGetc function reads a byte from the selected
serial port. The function will wait for the number of
system tics given by the 'Tics' argument before
returning 'timed out'. There are 18 tics to the
second.
To specify no waiting, call SioGetc with Tics = 0.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-1 : If timed out.
>0 : Character read.
Example int c; /* MUST be 'int', not 'char' !!! */
...
/* wait 9 tics for incoming character & display it */
if( (c=SioGetc(COM1,9)) != -1)
printf("Character is '%c'\n", c);
else puts("Timed out");
See Also SioUnGetc and SioPutc.
PCL4C Reference Manual Page 17
SioKeyPress
Function Detects if keyboard has been pressed.
Syntax int SioKeyPress()
Remarks The SioKeyPress function uses the BIOS to test the
keyboard for a key press (including control
characters).
SioKeyPress calls the BIOS directly without any
intermediate buffering or processing. It is usually
faster than using the C library.
Returns zero
Example if( SioKeyPress() )
{c = SioKeyRead();
/* echo character c */
SioCrtWrite(c)
}
See Also SioCrtWrite and SioKeyRead.
PCL4C Reference Manual Page 18
SioKeyRead
Function Reads the keyboard.
Syntax int SioKeyRead()
Remarks The SioKeyRead function uses the BIOS to read the
keyboard. It will wait until a character is typed.
SioKeyRead calls the BIOS directly without any
intermediate buffering or processing. It is usually
faster than using the C library.
Returns Character typed (including control codes).
Example if(SioKeyPress())
{/* fetch the character */
c = SioKeyRead();
/* echo to screen */
SioCrtWrite(c);
}
See Also SioCrtWrite and SioKeyRead.
PCL4C Reference Manual Page 19
SioInfo
Function Returns PCL4C library information.
Syntax int SioInfo(Cmd)
char Cmd; /* Command (VERSION or MODEL) */
Remarks The SioInfo function returns an integer code
corresponding to either the library version number or
the memory model that the library was assembled under.
SioInfo is provided so that you can verify the library
version number and memory model that a PCL4C library
was assembled under.
Returns VERSION ('V')
hex byte XY where version is denoted as X.Y
M_MODEL ('M')
0 Small
1 Compact
2 Medium
3 Large
Example char *Model[] = {"Small","Compact","Medium","Large"};
char Version;
char Model;
...
/* display library version */
Version = SioInfo(VERSION);
printf("Library version is %d.%d\n",
Version/16, Version%16);
/* display memory model */
Model = SioInfo(MODEL);
printf("Memory Model is %s\n", Model[Code]);
PCL4C Reference Manual Page 20
SioIRQ
Function Assigns an IRQ line and service routine to a port.
Syntax int SioIRQ(Port,IRQcode,ISRcode)
int Port; /* Port selected (COM1 thru COM4) */
int IRQcode; /* IRQ number [IRQ2..IRQ5] */
int ISRcode; /* Interrupt service # [0,1,2,3] */
Remarks The SioIRQ function assigns an IRQ line and
an interrupt service routine to a port. SioIRQ (like
SioUART) must be called before calling SioReset in
order to have any effect.
Unless you have a non-standard serial port
configuration (or don't want to run more than 2 ports
concurrently), you will not need to call SioIRQ. Be
EXTREMELY carefull with SioIRQ as it can lock your
machine up if given incorrect information.
In particular, remember that your port hardware must
generate the interrupt that you have specified. Also
be carefull about conflicting interrupt assignments.
IRQ 4 is the standard primary IRQ line while IRQ 3 is
the standard secondary IRQ line. The default IRQ
codes are thus:
Port IRQ ISR
COM1 IRQ4 FirstISR
COM2 IRQ3 SecondISR
COM3 IRQ4 ThirdISR
COM4 IRQ3 FourthISR
The IBM PS/2 uses non-standard COM3 and COM4 port
configurations as follows:
Port IRQ UART
COM3 IRQ3 0x3220
COM4 IRQ3 0x3228
Returns -4 : Port out of range. Expecting 0 to 3.
-15 : Port already enabled. SioReset has already been
called.
0 : Otherwise
Example /* use IRQ5 for COM3 */
SioUART(COM3,0x3220);
SioIRQ(COM3,IRQ5,ThirdISR);
/* we can now run 3 ports simultaneously */
See Also SioUART.
PCL4C Reference Manual Page 21
SioLine
Function Reads the line status register.
Syntax int SioLine(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioLine function reads the line status register.
The individual bit masks are as follows:
0x20 = Transmitter Buffer Empty.
0x10 = Break detected.
0x08 = Framming error.
0x04 = Parity error.
0x02 = Overrun error.
0x01 = Data ready.
The above are documented in the file PCL4C.H.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
>0 : Line status (rightmost byte of word).
Example int rc;
...
rc = LineStatus(Port);
if(rc & (FramingError|ParityError|OverrunError))
{if(rc & FramingError) puts("Framing Error");
if(rc & ParityError) puts("Parity Error");
if(rc & OverrunError) puts("Overrun Error");
}
else puts("No error");
See Also SioModem.
PCL4C Reference Manual Page 22
SioLoopBack
Function Does a UART loopback test.
Syntax int SioLoopBack(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks SioLoopBack makes use of the built in loopback test
capability of the INS8250 UART. Normally SioLoopBack
will never need to be called except if you suspect
that your UART is bad. See the LOOPBACK.C program.
Returns 0 : Loopback test is successfull.
-2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-12 : Loopback test fails.
Example /* test port */
if(SioLoopBack(Port))
puts("Loopback test has failed");
else puts("Loopback test has succeeded");
PCL4C Reference Manual Page 23
SioModem
Function Reads the modem status register.
Syntax int SioModem(Port, Mask)
int Port; /* Port selected (COM1 thru COM4) */
char Mask; /* Modem function mask */
Remarks The SioModem function reads the modem register. The
bit definitions for the function mask are as follows:
Bit PCL4C.H Name Function
7 DCD Data Carrier Detect
6 RI Ring Indicator
5 DSR Data Set Ready
4 CTS Clear To Send
3 DeltaDCD Delta DCD (DCD has changed)
2 DeltaRI Delta RI (RI has changed)
1 DeltaDSR Delta DSR (DSR has changed)
0 DeltaCTS Delta CTS (CTS has changed)
Bits 4 through 7 represent the absolute state of their
respective RS-232 inputs. Bits 0 through 3 repesent a
change in the state of their respective RS-232 inputs
since last read.
The above definitions are also in the PCL4C.H file for
use by your application program.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
>0 : Modem status (rightmost byte of word).
Example /* any change in DCD or CTS ? */
if(delta=SioModem(Port,DeltaDCD|DeltaCTS))
{status = SioModem(Port,DCD|CTS);
if(delta&DeltaDCD)
{if(status&DCD) c='T';
else c='F';
}
printf("DCD=%c\n",c);
}
if(delta&DeltaCTS)
{if(status&CTS)
{c='T'; else c='F';
printf("CTS=%c\n",c);
}
}
See Also SioCTS, SioDCD, SioDSR and SioRI.
PCL4C Reference Manual Page 24
SioParms
Function Sets parity, stop bits, and word length.
Syntax int SioParms(Port,ParityCode,StopBitsCode,WordLengthCode)
int Port; /* Port selected (COM1 thru COM4) */
int ParityCode; /* parity code [0,1,2] */
int StopBitsCode; /* stop bits code [0,1] */
int WordLengthCode; /* word length code [0,1,2,3] */
Remarks The SioParms function sets the parity, stop bits, and
word length. If the default parity (none), stop bits
(1), or word length (8) is not acceptable, then they
can be changed by calling SioParms. SioParms can be
called either before or after calling SioReset. See
file PCL4C.H.
Value Description PCL4C.H Name
ParityCode: *0 no parity NoParity
1 odd parity OddParity
3 even parity EvenParity
StopBitsCode: *0 1 stop bit OneStopBit
1 2 stop bits TwoStopBits
WordLengthCode: 0 5 data bits WordLength5
1 6 data bits WordLength6
2 7 data bits WordLength7
*3 8 data bits WordLength8
* = Default
Returns -4 : Port out of range. Expecting 0 to 3.
-7 : Bad parity code selected. Expecting 0 to 2.
-8 : Bad stop bits code. Expecting 0 or 1.
-9 : Bad word length code. Expecting 0 to 3.
Example /* set no parity, 1 stop bit, and 8 bit data for COM1 */
SioParms(COM1,NoParity,OneStopBit,WordLength8);
See Also SioReset.
PCL4C Reference Manual Page 25
SioPutc
Function Transmit a character over a serial line.
Syntax int SioPutc(Port,c)
int Port; /* Port selected (COM1 thru COM4) */
char c; /* character to send */
Remarks The SioPutc function transmits one character over the
selected serial line.
If flow control has been enabled, then SioPutc may
return a -1 (time out) if the number of tics specified
in the SioFlow function was exceeded waiting for the
modem to raise CTS. Refer to the User's Manual for a
discussion of flow control.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-1 : Timed out waiting for CTS (flow control enabled)
Example char crc;
char buffer[128];
...
/* transmit 128 byte buffer + CRC */
crc = 0;
for(i=0;i<128;i++)
{crc = crcupdate( buffer[i], crc);
SioPutc(Port, buffer[i]);
}
SioPutc(crc);
See Also SioGetc and SioFlow.
PCL4C Reference Manual Page 26
SioRead
Function Reads any UART register.
Syntax int SioRead(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioReset function directly reads the contents of
any of the 7 UART registers. This function is useful
when debugging application programs, and as a method
for verifying UART contents. Refer to the PCL Users
Manual for a discussion of the 7 UART registers.
Returns -3 : No buffer available. Call SioRxBuf first.
-4 : Port out of range. Expecting 0 to 3.
Example int Reg; /* UART register */
int Contents; /* contents of UART */
/* print contents of 7 UART registers */
for(Reg=0;Reg<7;Reg++)
{Contents = SioRead(Port,Reg);
printf("COM%d: UART Register %d = %d\n",
1+Port,Reg,Contents);
}
PCL4C Reference Manual Page 27
SioReset
Function Initialize a serial port for processing.
Syntax int SioReset(Port,BaudCode)
int Port; /* Port selected (COM1 thru COM4) */
int BaudCode; /* baud code or -1 */
Remarks The SioReset function initializes the selected serial
port. SioReset should be called after calling SioParm
and SioRxBuf but before making any other calls to
PCL4C. SioReset uses the parity, stop bits, and word
length value previously set if SioParm was called,
otherwise the default values (see SioParm) are used.
Recall that COM1 and COM3 share the same interrupt
vector and therefore cannot operate simultaneously.
Similiarly, COM2 and COM4 cannot operate
simultaneously. Any other combination of two ports can
be used.
By specifing NORESET (-1) for the baud rate code, the
port will NOT be reset. This is used to "take over" a
port from a host communications program that allows a
"DOS gateway". External protocols can be implemented
this way. See SioBaud for a list of the baud rate
codes, or see "PCL4C.H".
Returns -3 : No buffer available. Call SioRxBuf first.
-4 : Port out of range. Expecting 0 to 3.
-11 : Bad baud rate code selected. Expecting 0 to 9.
-13 : UART undefined. SioUART(Port,0) was called
previously.
-14 : Bad or missing UART. You may not have hardware
present.
-15 : Port already enabled. SioReset has already been
called.
-16 : Interrupt already in use.
Example char Buffer[128];
int rc;
...
SioRxBuf(COM1,Buffer,Size128);
rc = SioReset(Com1,Baud38400);
if(rc==0) puts("RESET ok");
else if(rc<0) SioError(rc);
else
{if(rc&OverrunError) puts("Overrun Error");
if(rc&ParityError) puts("Parity Error");
if(rc&FramingError) puts("Framing Error");
if(rc&BreakDetected) puts("Break Detected");
}
See Also SioBaud, SioParms, SioRxBuf, SioDone, and SioUART.
PCL4C Reference Manual Page 28
SioRI
Function Reads the Ring Indicator (RI) modem status bit.
Syntax int SioRI(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioRI function is used to read the Ring Indicator
(RI) modem status bit. Also see SioModem.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
0 : RI is clear.
>0 : RI is set (RING has occurred).
Example /* check for Ring */
if(SioRI(Port))
{puts("RING ");
/* process RING */
...
}
See Also SioDSR, SioCTS, SioDCD, and SioModem.
PCL4C Reference Manual Page 29
SioRTS
Function Sets, clears, or reads the Request to Send (RTS) line.
Syntax int SioRTS(Port,Cmd)
int Port; /* COM1 to COM4 */
char Cmd; /* RTS command (SET, CLEAR, or READ) */
Remarks The SioRTS function controls the Request to Send (RTS
bit in the modem control register.
The RTS line is used by some error correcting modems
to implement hardware flow control. RTS is dropped by
the computer to signal the modem not to send data, and
is raised to signal the modem to continue.
Refer to the User's Manual for a discussion of flow
control.
Commands (defined in PCL4C.H) are:
SET_LINE ('S') -- set RTS (ON)
CLEAR_LINE ('C') -- clear RTS (OFF)
READ_LINE ('R') -- read RTS
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-5 : Command is not one of 'S', 'C', or 'R'.
0 : RTS is OFF (READ_LINE Command).
>0 : RTS is ON (READ_LINE Command).
Example /* turn off RTS for modem */
SioRTS(Port,CLEAR);
See Also SioFlow and SioDTR.
PCL4C Reference Manual Page 30
SioRxBuf
Function Sets up receive buffers.
Syntax int SioRxBuf(Port,Buffer,SizeCode)
int Port; /* Port selected (COM1 thru COM4) */
char *Buffer /* Receive buffer */
int SizeCode; /* Buffer size code */
Remarks The SioRxBuf function passes the address and size of
the receive buffer to PCL4C. Recall that PCL4C
requires a receive buffer for each port in
simultaneous operation since the receive function is
interrupt driven. SioRxBuf passes the receive buffer
to PCL4C for both the primary (COM1/COM3) and
secondary (COM2/COM4) ports. It must be called before
any incoming characters can be received. SioRxBuf must
be called before SioReset. Buffer size codes are
listed in "PCL4C.H".
Size Code Buffer Size PCL4C.H Name
0 8 bytes Size8
1 16 bytes Size16
2 32 bytes Size32
3 64 bytes Size64
4 128 bytes Size128
5 256 bytes Size256
6 512 bytes Size512
7 1024 bytes Size1024 or Size1K
8 2048 bytes Size2048 or Size2K
9 4096 bytes Size4096 or Size4K
10 8192 bytes Size8192 or Size8K
11 16384 bytes Size16384 or Size16K
12 32768 bytes Size32768 or Size32K
Returns -4 : Port out of range. Expecting 0 to 3.
-10 : Bad buffer size code. Expecting 0 to 11.
Example char RxBuf[1024]; /* declare as global */
...
/* setup 1K receive buffer */
SioRxBuf(COM1, RxBuf, Size1024);
/* ready to call SioReset */
See Also SioReset.
PCL4C Reference Manual Page 31
SioRxFlush
Function To flush the receive buffer associated with the
specified port.
Syntax int SioRxFlush(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioRxFlush function will delete any characters in
the receive buffer for the specified port. After
execution, the receive buffer will be empty. Call
SioRxBuf after resetting a port in order to delete any
spurious characters.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
Example char buffer[1024];
...
/* setup receive buffer & reset port */
SioRxBuf(COM1,buffer,Size1024);
SioReset(COM1,Baud115200);
/* flush any spurious character */
SioRxFlush(COM1);
/* ready for serial processing ! */
...
See Also SioRxQue.
PCL4C Reference Manual Page 32
SioRxQue
Function Returns the number of characters in the receive queue.
Syntax int SioRxQue(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioRxQue function will return the number of
characters in the receive queue at the time of the
call. It can be used to implement XON/XOFF flow
control.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
Example #define XON 0x11
#define XOFF 0x13
int count;
char last = XON;
char Buffer[128];
...
SioRxBuf(COM1,Buffer,Size128);
/* implement XON / XOFF */
count = SioRxQue(COM1);
if((last==XON)&&(count>120))
{SioPutc(COM1,XOFF);
last = XOFF;
}
if((last==XOFF)&&(count<8))
{SioPutc(COM1,XON);
last = XON;
}
See Also SioRxFlush.
PCL4C Reference Manual Page 33
SioTimer
Function Returns the number of system clock tics since midnight.
Syntax long SioTimer()
Remarks The SioTimer function will return the number of system
clock tics since midnight, at 18.2065 tics per second.
This function is usefull for timing various functions.
Also see SioDelay.
Returns timer tics.
Example long time;
...
time = SioTimer();
...
printf("Elasped time = %ld tics\n",SioTimer() - time);
See Also SioDelay.
PCL4C Reference Manual Page 34
SioUART
Function Sets the UART base address.
Syntax int SioUART(Port,Address)
int Port; /* COM1 to COM4 */
int Address; /* UART address */
Remarks The SioUART function sets the UART base address for
the specified port. SioUART must be called before
SioReset in order to have effect. Be extremely sure
that you know what you are doing! Note that PCL4C uses
the standard PC/XT/AT port addresses, interrupt
request lines, and interrupt service vectors.
Therefore, this function is only needed for
non-standard ports.
Returns >0 : The previous base address for this port.
-4 : Port out of range. Expecting 0 to 3.
-15 : Port already enabled. SioReset has already been
called.
Example /* Record the fact that you don't have COM4 */
SioUART(COM4, 0);
See Also SioReset, SioIRQ.
PCL4C Reference Manual Page 35
SioUnGetc
Function "Un-gets" the last character read with SioGetc().
Syntax int SioUnGetc(Port,c)
int Port; /* Port selected (COM1 thru COM4) */
char c; /* character to unget */
Remarks The SioUnGetc function returns ("pushes") the
character back into the serial input buffer. The
character pushed will be the next character returned
by SioGetc. Only one character can be pushed back.
This function works just like the "ungetc" function in
the C language.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
Example /* push back c so next SioGetc will get it */
SioUnGetc(Port,c);
See Also SioReset.
PCL4C Reference Manual Page 36
Function Sumary
***********************************************************
* Function * Arg1 * Arg2 * Arg3 * Arg4 *
***********************************************************
* SioBaud * Port * BaudCode * * *
* SioBrkKey * * * * *
* SioBrkSig * Port * Cmd * * *
* SioCrtWrite * Ch * * * *
* SioCTS * Port * * * *
* SioDCD * Port * * * *
* SioDelay * Tics * * * *
* SioDone * Port * * * *
* SioDSR * Port * * * *
* SioDTR * Port * Cmd * * *
* SioError * Code * * * *
* SioFIFO * Port * FIFOcode * * *
* SioFlow * Port * Tics * * *
* SioGetc * Port * Tics * * *
* SioKeyPress * * * * *
* SioKeyRead * * * * *
* SioInfo * Cmd * * * *
* SioIRQ * Port * IRQcode * ISRcode * *
* SioLine * Port * * * *
* SioLoopBack * Port * * * *
* SioModem * Port * Mask * * *
* SioParms * Port * Parity * StopBits *WordLength*
* SioPutc * Port * Ch * * *
* SioRead * Port * Register * * *
* SioReset * Port * BaudCode * * *
* SioRI * Port * * * *
* SioRTS * Port * Cmd * * *
* SioRxBuf * Port * Buffer * SizeCode * *
* SioRxFlush * Port * * * *
* SioRxQue * Port * * * *
* SioTimer * * * * *
* SioUART * Port * Address * * *
* SioUnGetc * Port * Ch * * *
***********************************************************
[ 33 functions ]
PCL4C Reference Manual Page 37
Error Code Summary
*****************************************************************
* Code * Description *
*****************************************************************
* 0 * No error. *
* -1 * Timeout waiting for I/O. *
* -2 * Port not enabled. Call SioReset first. *
* -3 * No buffer available. Call SioRxBuf first. *
* -4 * Port out of range. Expected 0 to 3. (COM1 = 0) *
* -5 * Expected 'S', 'C', or 'R' as 2nd argument. *
* -6 * Expected 'A', 'C', or 'D' as 2nd argument. *
* -7 * Bad parity code specified. Expected 0 to 7. *
* -8 * Bad stop bits code specified. Expected 0 or 1. *
* -9 * Bad wordlength code specified. Expected 0 to 3. *
* -10 * Bad buffer size code specified. Expected 0 to 11. *
* -11 * Bad baud rate code. Expected 0 to 9. *
* -12 * Loopback test fails. *
* -13 * UART undefined. *
* -14 * Missing or bad UART. *
* -15 * Port already enabled. *
* -16 * Interrupt already in use. *
*****************************************************************
PCL4C Reference Manual Page 38
